/**
 * 
 */
package com.I9lou.se.lurker.index;

import java.util.Set;
import java.util.concurrent.CountDownLatch;

import org.apache.lucene.index.IndexWriter;

import com.I9lou.se.lurker.cache.ServiceCache;

/**
 * IndexWriter实例工厂，同一个索引文件夹只对应一个IndexWriter实例。
 * 
 * 注意：由该工厂获取的IndexWriter实例不可直接在外部调用IndexWriter#close()来进行关闭操作，
 * 关闭操作应调用工厂{@link #close(String)}方法进行。
 * 
 * 注意：索引文件夹名由两部分组成，并用"-"符号进行分割，第一部分为搜索应用ID，
 * 第二部分为不包含"-"符号的任意合法的文件夹名称字符。该规则不允许被修改，
 * 其他服务可依赖此规则根据索引文件夹名称获取对应的搜索应用ID。 
 * 
 * @author chenwei
 * @date 2011-03-07
 */
public interface IndexWriterFactory {
	
	/**
	 * 根据索引文件夹名称获得对应的IndexWriter实例，如果指定的索引文件夹目前不可用（例如正在执行关闭操作），
	 * 则返回null。
	 * 
	 * 注意：通过此方法获取的IndexWriter实例不可直接在外部调用IndexWriter#close()来进行关闭操作，
	 * 关闭操作应调用工厂{@link #close(String)}方法进行。
	 * 
	 * @param indexDirName ex:101-xxx。
	 * @return indexWriter
	 * @throws IllegalArgumentException indexDirName为空时抛出此异常
	 */
	public IndexWriter get(String indexDirName);
	
	/**
	 * 获得当前所有可用的索引目录名称列表
	 * @return names
	 */
	public Set<String> getIndexDirNames();
	
	/**
	 * 获取跟本IndexWriterFactory相关的IndexWriter缓存池
	 * @return
	 */
	public ServiceCache<IndexWriter> getPool();
	
	/**
	 * 根据索引文件夹名称关闭其在当前工厂所对应的IndexWriter实例。
	 * 此方法通常在针对IndexWriter实例进行操作时遇到OutOfMemoryError异常后调用
	 * @param indexDirName
	 */
	public void close(String indexDirName);
	
	/**
	 * 用于监控IndexWriterFactory是否可以执行关闭操作的锁:
	 * 当所有外部执行提交操作的调度器都停止后,开始执行factory的释放
	 * @return
	 */
	public CountDownLatch getIndexWriterLatch();
}
